package com.studyweb.service;

import com.studyweb.pojo.entity.UserAchievement;

import java.util.List;

/**
 * 用户成就服务接口
 * 
 * @author StudyWeb Team
 * @since 1.0.0
 */
public interface UserAchievementService {
    
    /**
     * 根据ID查询用户成就
     * 
     * @param id 用户成就ID
     * @return 用户成就信息
     */
    UserAchievement getById(Long id);
    
    /**
     * 根据用户ID查询用户成就
     * 
     * @param userId 用户ID
     * @return 用户成就列表
     */
    List<UserAchievement> listByUserId(Long userId);
    
    /**
     * 根据用户ID和成就类别查询用户成就
     * 
     * @param userId 用户ID
     * @param category 成就类别
     * @return 用户成就列表
     */
    List<UserAchievement> listByUserIdAndCategory(Long userId, String category);
    
    /**
     * 检查用户是否已获得指定成就
     * 
     * @param userId 用户ID
     * @param achievementId 成就ID
     * @return 是否已获得
     */
    boolean hasAchievement(Long userId, Long achievementId);
    
    /**
     * 授予用户成就
     * 
     * @param userId 用户ID
     * @param achievementId 成就ID
     * @return 用户成就信息
     */
    UserAchievement grantAchievement(Long userId, Long achievementId);
    
    /**
     * 领取成就积分奖励
     * 
     * @param userAchievementId 用户成就ID
     * @param userId 用户ID
     * @return 是否领取成功
     */
    boolean claimAchievementPoints(Long userAchievementId, Long userId);
    
    /**
     * 检查并授予用户签到相关成就
     * 
     * @param userId 用户ID
     * @param consecutiveDays 连续签到天数
     * @param totalCheckins 累计签到天数
     * @return 新获得的成就列表
     */
    List<UserAchievement> checkAndGrantCheckinAchievements(Long userId, int consecutiveDays, int totalCheckins);
    
    /**
     * 更新用户成就显示状态
     * 
     * @param id 用户成就ID
     * @param isDisplayed 是否显示
     * @return 是否成功
     */
    boolean updateDisplayStatus(Long id, boolean isDisplayed);
    
    /**
     * 删除用户成就
     * 
     * @param id 用户成就ID
     * @return 是否成功
     */
    boolean delete(Long id);
    
    /**
     * 获取用户成就数量
     * 
     * @param userId 用户ID
     * @return 成就数量
     */
    int countByUserId(Long userId);
    
    /**
     * 获取用户在特定类别的成就数量
     * 
     * @param userId 用户ID
     * @param category 成就类别
     * @return 成就数量
     */
    int countByUserIdAndCategory(Long userId, String category);
    
    /**
     * 获取用户积分
     * 
     * @param userId 用户ID
     * @return 用户积分
     */
    int getUserPoints(Long userId);
}